PATHMac OS 8 Developer Documentation > Files > Navigation Services >

Programming With Navigation Services 1.1

Opening Files

The function NavGetFile displays an Open dialog box that prompts the user to select one or more files to open, as shown in Figure 9 .

Figure 9 Open dialog box

For a description of the elements of an Open dialog box, see User Interface.

Note

You are strongly encouraged to make all Navigation Services dialog boxes movable by providing an event-handling function. For more information, see Handling Events.


Providing File Opening Options

The Open dialog box's Show pop-up menu allows the user to choose the file types displayed by the browser list. The list of available file types is built from information provided by your application when it calls the NavGetFile function and by the Translation Manager. If you don't want the Show pop-up menu button to be displayed, specify the kNavNoTypePopup constant in the dialogOptionFlags field of a structure of type NavDialogOptions when you pass this structure in the dialogOptions parameter of a file-opening function such as NavGetFile .

Navigation Services uses the Translation Manager to produce a list of file types that your application is capable of translating and displays the list to the user through an expanded Show pop-up menu. Figure 10 shows an example of a Show pop-up menu with file translation options.

Figure 10 A Show pop-up menu with file translation options

The first section of the Show menu contains an item called " All Readable Documents." If the user selects this item, the browser list displays all files of the types shown in the second and third sections of the menu.

The second section of the Show menu contains an item called "All <app name> Documents" followed by your application's "native" file types. Native file types are those types you provide in the typeList parameter of the file-opening function. This parameter has the same format as an 'open' resource and may be loaded from a resource or passed in as a structure created on the fly.

Note

Navigation Services will not automatically load an 'open' resource. Your application must pass a pointer to it in the typeList parameter of the file-opening function.

Your application must also contain a 'kind' resource with entries for each type of file that you want to include in the typeList parameter. If you don't provide an entry for a file type, Navigation Services returns a result of kNavMissingKindStringErr (-5699). For more information on 'kind' resources, see Inside Macintosh: More Macintosh Toolbox .

Listing a file type in the typeList parameter generally limits you to displaying only those files created by your application. If you specify the kNavSelectAllReadableItem constant in the dialogOptionFlags field of the NavDialogOptions structure you pass in the dialogOptions parameter, or if the user selects All Readable Items from the Show menu, Navigation Services will ignore the application signature specified in the typeList parameter and display all documents of the specified types. If you choose not to specify file types in the typeList parameter, you can show all files of a particular type in the browser list by using an application-defined filter function. Using a filter function would, for example, allow you to show all text files, regardless of which application created them. For more information on filter functions, see Filtering File Objects.

The third section of the expanded Show pop-up menu contains a list of translatable file types provided by the Translation Manager. Typical names for these entries describe an application document type, such as "MoviePlayer document" in Figure 10 . Navigation Services automatically opens and translates file types recognized by the Translation Manager unless you supply the kNavDontAutoTranslate constant in the dialogOptionFlags field of the NavDialogOptions structure you pass in the dialogOptions parameter.

Note

The translatable files section does not appear if you supply the kNavDontAddTranslateItems constant in the dialogOptionFlags field of the NavDialogOptions structure you pass in the dialogOptions parameter.

The last section of the pop-up menu is reserved for the " All Documents" menu item. This item appears if your application supplies the kNavAllFilesInPopup constant in the dialogOptionFlags field of the NavDialogOptions structure you pass in the dialogOptions parameter. This option allows the display of all files, regardless of your application's ability to translate or open them directly. A resource editing application, for example, might take advantage of this option.


Translating Files on Open

If the user selects a file type that is not passed in the typeList parameter, the chosen file must be translated. If the user opens a file called "Doc1" that requires translation, Navigation Services creates a new file called "Doc1 (converted)" with the appropriate file type, in the same directory as the original file. The NavGetFile function automatically performs the translation before returning. However, you can disable this feature by supplying the kNavDontAutoTranslate constant in the dialogOptionFlags field of the structure of type NavDialogOptions you pass in the dialogOptions parameter of the file-opening function. If you disable automatic translation, it is left to your application to call the function NavTranslateFile as needed.

You can obtain translation information from the structure of type NavReplyRecord that you passed in the reply parameter of the file-opening function. When the file-opening function returns, the fileTranslation field of the NavReplyRecord structure points to an array of translation records. This array contains one translation record for each file selection identified in the selection field of the NavReplyRecord structure. If you disable automatic translation, you can use the translation records to provide your own translation.

Note

If a file described in the selection field of the NavReplyRecord structure does not require translation, its corresponding translation record will be empty.


A Sample File-Opening Function

Listing 1 shows a sample function illustrating one way to call the function NavGetFile . This listing shows how to get default options, modify the options, use an 'open' resource, and open multiple files.

Note

This listing and other code samples in this document show how to handle an Apple event descriptor of type 'typeFSS' . Your application should not assume that Navigation Services returns descriptors of any particular type.

Listing 1 A sample file-opening function

OSErr MyOpenDocument(const FSSpecPtr defaultLocationfssPtr)
{
    NavDialogOptions    dialogOptions;
    AEDesc              defaultLocation;
    NavEventUPP         eventProc = NewNavEventProc(myEventProc);
    NavObjectFilterUPP  filterProc =
                        NewNavObjectFilterProc(myFilterProc);
    OSErr               anErr = noErr;
    
    //  Specify default options for dialog box
    anErr = NavGetDefaultDialogOptions(&dialogOptions);
    if (anErr == noErr)
    {
        //  Adjust the options to fit our needs
        //  Set this option
        dialogOptions.dialogOptionFlags |= kNavSelectDefaultLocation;
        //  Clear this one
        dialogOptions.dialogOptionFlags ^= kNavAllowPreviews;
        
        anErr = AECreateDesc(typeFSS, defaultLocationfssPtr,
                             sizeof(*defaultLocationfssPtr),
                             &defaultLocation );
        if (anErr == noErr)
        {
            // Get 'open' resource. A nil handle being returned is OK,
            // this simply means no automatic file filtering.
            NavTypeListHandle typeList = (NavTypeListHandle)GetResource(
                                        'open', 128);
            NavReplyRecord reply;
            
            anErr = NavGetFile (&defaultLocation, &reply, &dialogOptions,
                                eventProc, nil, filterProc,
                                typeList, nil);
            if (anErr == noErr && reply.validRecord)
            {
                //  Deal with multiple file selection
                long    count;
                
                anErr = AECountItems(&(reply.selection), &count);
                if (anErr == noErr)
                {
                    longindex;
                    
                    for (index = 1; index <= count; index++)
                    {
                        AEKeyword   theKeyword;
                        DescType    actualType;
                        Size        actualSize;
                        FSSpec      documentFSSpec;
                        
                        anErr = AEGetNthPtr(&(reply.selection), index,
                                            typeFSS, &theKeyword,
                                            &actualType,&documentFSSpec,
                                            sizeof(documentFSSpec),
                                            &actualSize);
                        if (anErr == noErr)
                        {
                            anErr = DoOpenFile(&documentFSSpec);
                        }
                    }
                }
                //  Dispose of NavReplyRecord, resources, descriptors
                anErr = NavDisposeReply(&reply);
            }
            if (typeList != NULL)
            {
                ReleaseResource( (Handle)typeList);
            }
            (void) AEDisposeDesc(&defaultLocation);
        }
    }
    DisposeRoutineDescriptor(eventProc);
    DisposeRoutineDescriptor(filterProc);
    return anErr;
}

Listing 2 illustrates how your application can open a list of documents by sending itself Apple events.

Listing 2 A sample file-opening function using Apple events

static void MyOpenWithEvent(FSSpecPtr defaultLocationfssPtr)
{
    AEDesc              defaultLocation;
    NavReplyRecord      navReply;
    NavDialogOptions    dialogOptions;
    NavTypeListHandle   typeList;
    NavEventUPP         eventProc = NewNavEventProc(myEventProc);
    NavObjectFilterUPP  filterProc =
                        NewNavObjectFilterProc(myFilterProc);
    OSErr               anErr = noErr;
    
    //  Specify default options for dialog box
    anErr = NavGetDefaultDialogOptions( &dialogOptions );
    if (anErr == noErr)
    {
        //  Adjust options to fit our needs
        //  Set this option
        dialogOptions.dialogOptionFlags |= kNavSelectDefaultLocation;
        //  Clear this option
        dialogOptions.dialogOptionFlags ^= kNavAllowPreviews;
        
        anErr = AECreateDesc(typeFSS, defaultLocationfssPtr,
                             sizeof(*defaultLocationfssPtr),
                             &defaultLocation );
        if (anErr == noErr)
        {
            // Get 'open' resource. A nil handle being returned is OK,
            // this simply means no automatic file filtering.
            typeList = (NavTypeListHandle) GetResource('open', 128);
            
            anErr = NavGetFile( &defaultLocation, &navReply,
                                &dialogOptions, eventProc,
                                nil, filterProc, typeList, nil);
    
    if (anErr == noErr && navReply.validRecord)
    {
        ProcessSerialNumber processSN = {0, kCurrentProcess};
        AEAddressDesc       targetAddress = {typeNull, nil};
        AppleEvent          theEvent = {typeNull, nil};
        AppleEvent          theReply = {typeNull, nil}
        //  This is an event targeted at the current application
        anErr = AECreateDesc(typeProcessSerialNumber, &processSN,
                             sizeof(ProcessSerialNumber),
                             &targetAddress);
        if ( anErr == noErr )
        {
            //  Create an open documents Apple event
            anErr = AECreateAppleEvent(kCoreEventClass, kAEOpenDocuments,
                                        &targetAddress,
                                        kAutoGenerateReturnID,
                                        kAnyTransactionID, &theEvent);
            (void) AEDisposeDesc(&targetAddress);
        }
        if (anErr == noErr)
        {
            //  Put file list into open document Apple event
            anErr = AEPutParamDesc( &theEvent, keyDirectObject,
                                    &(navReply.selection) );
        }
        if (anErr == noErr)
        {
            //  Send open doc event to our app and dispose of descriptors
            anErr = AESend( &theEvent, &theReply, kAENoReply,
                            kAENormalPriority,
                            kAEDefaultTimeout, nil, nil);
            (void) AEDisposeDesc(&theEvent);
            (void) AEDisposeDesc(&theReply);
        }
        (void) NavDisposeReply(&navReply);
    }
    return;
}
© 1998 Apple Computer, Inc. – (Last Updated 23 Nov 98)